/*+==========================================================================
  File:      TUTORIAL.TXT

  Summary:   This file contains an overview of the OLE tutorial code
             samples. These samples reside in a directory tree described
             below. Instructions for installing this tree are not
             included here, but this file provides general information for
             setting up your computer environment to build the code
             samples.

  Origin:    7-3-96: atrent - Revised for OLE Tutorial Code Sample series.

----------------------------------------------------------------------------
  This file is part of the Microsoft OLE Tutorial Code Samples.

  Copyright (C) Microsoft Corporation, 1996. All rights reserved.

  This source code is intended only as a supplement to Microsoft
  Development Tools and/or online documentation. See these other
  materials for detailed information regarding Microsoft code samples.

  THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
  PARTICULAR PURPOSE.
==========================================================================+*/


Tutorial Code Samples

The OLE tutorial code samples reside in the following directory tree,
organized in a graduated sequence of tutorial lessons. The numbered order
listed below is the intended order of the lessons. Each lesson
illustrates a major feature of OLE technology. Most lessons build on the
ones that came earlier in the sequence.

Each code sample directory contains a description of the sample's external
operation and a narrative code tour of the internal construction (based on
the specific goal of the tutorial lesson). This tutorial narrative
resides in a stand-alone <lesson>.TXT file--where <lesson> is the name of
the lesson/code sample. There is a narrative .TXT file corresponding to
each tutorial code sample. Additional details on the internal mechanisms
can be found in code comments in each source file.

  COM        - This file, MAKEALL.BAT, etc.
    APPUTIL  - Common classes and utility functions in a static library
    INC      - Common include directory used by the code samples
    LIB      - Common library directory used by the code samples
    EXESKEL  - Lesson  1: Win32 Basics: OLE EXE Skeleton Application
    DLLSKEL  - Lesson  2: Win32 Basics: OLE DLL Skeleton
    DLLUSER  - Lesson  3: Win32 Basics: EXE User of a DLL
    COMOBJ   - Lesson  4: COM Objects: Containment and Aggregation in a DLL
    COMUSER  - Lesson  5: COM Objects: Nested Aggregation in EXE User
    REGISTER - Lesson  6: COM Components: Component Registration
    DLLSERVE - Lesson  7: COM Components: Component DLL Server
    DLLCLIEN - Lesson  8: COM Components: Client Application of DLL Server
    LICSERVE - Lesson  9: COM Components: DLL Licensed Server
    LICCLIEN - Lesson 10: COM Components: Client App of Licensed Server
    MARSHAL  - Lesson 11: COM Components: Standard Marshaling
    LOCSERVE - Lesson 12: COM Components: Local Server
    LOCCLIEN - Lesson 13: COM Components: Client App of Local Server
    APTSERVE - Lesson 14: COM Components: Apartment Threaded Local Server
    APTCLIEN - Lesson 15: COM Components: Client of Apartment Threaded Server
    REMCLIEN - Lesson 16: COM Components: DCOM Remote Client
    FRESERVE - Lesson 17: COM Components: Free Threaded Server
    FRECLIEN - Lesson 18: COM Components: Client of Free Threaded Server
    CONSERVE - Lesson 19: COM Components: Connectable Object Server
    CONCLIEN - Lesson 20: COM Components: Client of Connectable Object Server
    STOSERVE - Lesson 21: OLE Services: Structured Storage Server
    STOCLIEN - Lesson 22: OLE Services: Client of Structored Storage Server

Throughout the sample sequence a clear differentiation is maintained
between client and server, with a separate lesson sample for each.
Usually, each client/server pair covers an area of OLE technology. Here is
an overview of the technologies covered by the lessons.

Basic Win32 application programming is covered in the APPUTIL, EXESKEL,
DLLSKEL, and DLLUSER lessons. APPUTIL provides a utility framework for
building Win32 applications. It also contains some tools needed for
tutorial purposes. EXESKEL shows a basic Win32 skeleton EXE application
built using APPUTIL. DLLSKEL and DLLUSER simularly show a basic Win32 DLL
(Dynamic Link Library) skeleton and how to access it from an EXE user
application.

Basic COM object construction, custom interfaces, and techniques for
coding their reuse using aggregation and containment are covered in COMOBJ
and COMUSER.

Basic COM component construction, class factories, and techniques for
housing COM objects in COM component servers are covered in REGISTER,
DLLSERVE, and DLLCLIEN.

COM component Licensing using IClassFactory2 is covered in LICSERVE and
LICCLIEN.

Out-of-Process local servers and the standard marshaling of custom
interfaces are covered in MARSHAL, LOCSERVE, and LOCCLIEN.

Multi-threaded apartment model server and client construction are covered
in APTSERVE and APTCLIEN.

DCOM (Distributed COM) with custom interfaces operating between client and
server across machine boundaries is covered in REMCLIEN.

Free-threaded COM components and their access by muli-threaded clients are
covered in FRESERVE and FRECLIEN.

Connectable COM object technology is covered in CONSERVE and CONCLIEN.

Structured storage using OLE's compound file technology is covered in
STOSERVE and STOCLIEN.


Building the Code Samples

Aside from the dependence on the common code in the sibling APPUTIL, INC,
and LIB directories, many code samples are self-contained. You need to
build APPUTIL before you build any of the other code samples. Some
samples later in the sequence may work with the compiled results of
earlier samples. These code sample interdependencies are as follows.

Any:      Build of any code sample needs prior build of APPUTIL.
DLLUSER:  Build or run needs prior build of DLLSKEL.
COMUSER:  Build or run needs prior build of COMOBJ.
DLLSERVE: Build needs prior build of REGISTER.
DLLCLIEN: Run needs prior build of DLLSERVE.
LICSERVE: Build needs prior build of REGISTER.
LICCLIEN: Run needs prior build of LICSERVE and DLLSERVE.
MARSHAL:  Build needs prior build of REGISTER.
LOCSERVE: Build or run needs prior build of REGISTER and MARSHAL.
LOCCLIEN: Run needs prior build of LOCSERVE.
APTSERVE: Build or run needs prior build of REGISTER and MARSHAL.
APTCLIEN: Run needs prior build of APTSERVE.
REMCLIEN: Build or run needs prior build of REGISTER and MARSHAL on local
          (client) machine. Run needs prior build of REGISTER, MARSHAL,
          and APTSERVE on remote (server) machine.
FRESERVE: Build needs prior build of REGISTER.
FRECLIEN: Run needs prior build of FRESERVE.
CONSERVE: Build needs prior build of REGISTER.
CONCLIEN: Run needs prior build of CONSERVE.

All of these code samples should build on your properly installed Win32
SDK platform. To successfully run the REMCLIEN, FRESERVE, and FRECLIEN
samples requires system facilities that are only available in more recent
versions of the 32-bit Windows operating systems. REMCLIEN, FRESERVE, and
FRECLIEN require the Windows NT Workstation version 4.0 or later, which
includes releases as early as the version 4.0 Beta 1 release. The
REMCLIEN, FRESERVE, and FRECLIEN samples will build but will not run on
the Windows 95 operating system until Distributed COM (DCOM) and free
threaded COM are supported in that operating system.

Each directory has the necessary source files to build and run the sample.
The parent COM directory has a MAKEALL.BAT file, which you can run to make
all the code samples in the branch below COM. See the MAKEALL.BAT file
for details on usage. If your environment is set up to build Win32 C++
applications, you can simply run MAKEALL.BAT from the directory where it
resides to build all the code samples in the branch below. MAKEALL
ensures the correct order to the build so that all the code sample
dependencies are satisfied.

The COM directory also has a makefile that builds all the tutorial code
samples using options similar to those supported by MAKEALL.BAT. See this
makefile for details on options. This makefile assumes that the entire
code samples branch is installed as part of the Win32 SDK. Currently this
location has a path similar to <d>:\MSTOOLS\SAMPLES\OLE\COM, where <d> is
the installation drive. If you have extracted the tutorial code sample
branch (directory COM and below) to another location outside the Win32
SDK, then use MAKEALL.BAT to compile all the samples in the branch.

Two batch files, REGALL.BAT and UNREGALL.BAT, are also provided in the COM
directory to register and unregister all COM servers in the tutorial code
sample series. To register all servers, run REGALL.BAT file from the COM
directory. To unregister all servers, run UNREGALL.BAT in the same manner.
These batch files require a prior build of the REGISTER, MARSHAL,
DLLSERVE, LICSERVE, LOCSERVE, APTSERVE, FRESERVE, and CONSERVE code
samples. If you perform a normal build of the code samples, the server
makefiles will automatically register the servers. In this case you do not
need to run the REGALL.BAT batch file.

Run the CLEANALL.BAT batch file to clean up all the code samples. All of
the COM servers that are built in the tutorial code samples are
unregistered from the registry. All executable EXE and DLL files are
deleted. All debug symbol files are deleted. Files that are generated in a
variety of build environments are also deleted.

To build any of the code samples, your computer environment must be set up
to build Win32 C++ applications with a properly installed 32-bit C++
compiler, linker, and resource compiler that are compatible with Microsoft
Visual C++ 2.x or above, and a properly installed Win32 SDK. It is
usually wise to install the Win32 SDK last. Alternatively, and exclusive
of the Win32 SDK, you may use an installed 32-bit C++ integrated
development environment (IDE). But to do so requires that you treat the
generic makefiles provided as external to your IDE. These makefiles
require a Microsoft NMAKE-compatible make utility.

The Win32 SDK provides a SETENV.BAT file located in the \MSTOOLS directory
that you can run to set up your environment for building applications that
use the Win32 SDK.

You can also set up your environment by adding something like the
following to your AUTOEXEC.BAT file. Under Windows 95, you can manually
edit the AUTOEXEC.BAT file to include these commands in it. Under Windows
NT, you can edit or add these settings to your environment variables using
the System dialog that you can run from the Control Panel.

  SET INCLUDE=E:\MSTOOLS\INCLUDE;D:\MSDEV\INCLUDE;D:\MSDEV\MFC\INCLUDE
  SET LIB=E:\MSTOOLS\LIB;D:\MSDEV\LIB;D:\MSDEV\MFC\LIB
  SET MSTOOLS=E:\MSTOOLS
  SET CPU=i386
  SET PATH=C:\WIN95;C:\WIN95\COMMAND;C:\DOS;E:\MSTOOLS\BIN;D:\MSDEV\BIN

These settings are appropriate for an Intel 80386 or better platform
running Windows 95 with both Microsoft Visual C++ and the Win32 SDK
installed. On this system, Visual C++ is installed under the D:\MSDEV
directory. The Win32 SDK is installed under the E:\MSTOOLS directory.
Your disk configuration may be different. The Win32 SDK E:\MSTOOLS
directories are all earlier in each path sequence where they must be
specified. This sequence assumes that command line compilations are
intended to be run in the Command Prompt window.

The D:\MSDEV\MFC\INCLUDE and D:MSDEV\MFC\LIB directories are shown in
the INCLUDE and LIB paths, but they are not required to build the tutorial
code samples. In this particular setup, Microsoft Foundation Class (MFC)
applications are being compiled, as well as straight OLE and Win32
applications.

The CPU environment variable is defined to control the Win32 builds,
depending on the platform. Current possible values are i386, MIPS, ALPHA,
and PPC. For more details, see the WIN32.MAK file provided in the Win32
SDK in the \MSTOOLS\INCLUDE directory. All of the OLE tutorial code sample
makefiles include WIN32.MAK.

The makefiles for each of the code samples in this series are generic Win32
makefiles and are meant to be built from the Command Prompt window. They
assume Microsoft compiler and linker tools and will probably need some
modification to work with other tools. Most compiler/linker command line
switches are specified by macros that are defined in the WIN32.MAK
makefile include file (supplied as part of the Win32 SDK). The
MAKEALL.BAT file and each respective code sample makefile support the
following common options for invocation from the Command Prompt window to
control the nature of the build:

  NMAKE invocation   MAKEALL invocation    Effect
  -----------------  --------------------  ---------------------------------
  nmake              makeall               Compile with debug info.
  nmake nodebug=1    makeall "nodebug=1"   Compile without debug info.
  nmake profile=1    makeall "profile=1"   Compile with profiling info.
  nmake tune=1       makeall "tune=1"      With working set tuner info.
  nmake unicode=1    makeall "unicode=1"   Compile for UNICODE.
  nmake clean        makeall clean         Delete temporary binaries.
  nmake cleanall     makeall cleanall      Delete all generated files.

For the MAKEALL.BAT invocations you need the quotes as shown. The nodebug,
profile, and tune options are mutually exclusive: you may use only one of
them for a given compilation/link. To compile the samples to run with
UNICODE strings, use the unicode=1 option. The default is to compile for
the traditional ANSI string support, because you can then easily run on
either Windows NT or Windows 95. Currently, you must compile without
UNICODE to run these code samples on Windows 95. You can freely compile
and run with or without UNICODE on Windows NT. Be careful that APPUTIL is
always compiled with the same options as the other code samples you may be
separately compiling. This is especially true for the unicode=1 option.

Most C++ IDEs can also recognize these makefiles as external and yet still
give many of the edit-build-debug benefits of the IDE. For example, in
Microsoft Visual C++ 4.x, you can simply use the File menu's Open
Workspace choice to produce a rudimentary project .MAK file by opening the
code sample's makefile.  From there you can use the editor, debugger, and
project facilities to edit, compile, link, and debug. Some of the visual
IDEs can also easily generate one of their native project makefiles, given
the existing source files of a code sample. If you are using such an IDE,
generating such a native project makefile may be worthwhile. See your IDE
documentation for details on using external makefiles or on creating a
native project makefile using existing source files.


Extracting the Code Samples

Though the code samples are divided into tutorial lessons, the appropriate
sample groupings can easily be extracted from the collection. Most of the
individual sample directories are meant to work in conjunction with at
least one other sample directory. The component-related samples consist
of a client and server pair, with the server requiring the use of the
REGISTER sample utility. Here is a summary of the sample groupings and how
to extract each group as a buildable unit. For each sample grouping, copy
the content of the directory structure shown.

For the Win32 EXE skeleton application:
  COM
    APPUTIL
    INC
    LIB
    EXESKEL

For the Win32 DLL skeleton:
  COM
    APPUTIL
    INC
    LIB
    DLLSKEL
    DLLUSER

For the basic COM object samples:
  COM
    APPUTIL
    INC
    LIB
    COMOBJ
    COMUSER

For the basic in-process DLL component client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    DLLSERVE
    DLLCLIEN

For the licensed component client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    LICSERVE
    LICCLIEN

For the standard marshaling sample:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL

For the out-of-process local client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL
    LOCSERVE
    LOCCLIEN

For the apartment model client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL
    APTSERVE
    APTCLIEN

For the DCOM (Distributed COM) client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL
    APTSERVE
    REMCLIEN

For the free threading client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    FRESERVE
    FRECLIEN

For the connectable COM object client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    CONSERVE
    CONCLIEN

For the structured storage client/server samples:
  COM
    APPUTIL
    INC
    LIB
    REGISTER
    STOSERVE
    STOCLIEN


Coding Style Conventions

Because this tutorial provides a graduated sequence of code samples,
certain coding style conventions are used. The "Hungarian" notation
conventions are used. These have become a common coding practice in Win32
programming. They include variable prefix notations that give to variable
names a suggestion of the type of the variable. The following prefixes
are common:

  a       Array
  b       BOOL (int)
  by      Unsigned Char (byte)
  c       Char
  cb      Count of bytes
  cr      Color reference value
  cx      Count of x (short)
  dw      DWORD (unsigned long)
  f       Flags (usually multiple bit values)
  fn      Function
  g_      global
  h       Handle
  i       Integer
  l       Long
  lp      Long pointer
  m_      Data member of a class
  n       Short int
  p       Pointer
  s       String
  sz      Zero terminated String
  tm      Text metric
  u       Unsigned int
  ul      Unsigned long (ULONG)
  w       WORD (unsigned short)
  x,y     x, y coordinates (short)

These are often combined, as in:

  pszMyString    A pointer to a string.
  m_pszMyString  A pointer to a string that is a data member of a class.

Other conventions are:

  CMyClass          Prefix 'C' for C++ class names.
  COMyObjectClass   Prefix 'CO' for COM object class names.
  CFMyClassFactory  Prefix 'CF' for COM class factory names.
  IMyInterface      Prefix 'I' for COM interface class names.
  CImpIMyInterface  Prefix 'CImpI' for COM interface implementation classes.

Because the OLE tutorial code samples are meant to be study devices in
addition to being coding skeletons, some consistent conventions for
comment header blocks are used. They are:


File Header

/*+==========================================================================
  File:      MYFILE.EXT

  Summary:   Brief summary of the file contents and purpose.

  Classes:   Classes declared or used (in source files).

  Functions: Functions exported (in source files).

  Origin:    Indications of where content may have come from. This is not
             a change history but rather a reference to the
             "editor-inheritance" behind the content or other indications
             about the origin of the source.

----------------------------------------------------------------------------
  Copyright and Legal notices.
  Copyright and Legal notices.
==========================================================================+*/


Plain Comment Block

/*---------------------------------------------------------------------------
  Plain block of comment text that usually takes more than several lines.
  Plain block of comment text that usually takes more than several lines.
---------------------------------------------------------------------------*/


Class Declaration Header

/*C+C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C
  Class:    CMyClass

  Summary:  Short summary of purpose and content of CMyClass.
            Short summary of purpose and content of CMyClass.

  Methods:  MyMethodOne
              Short description of MyMethodOne.
            MyMethodTwo
              Short description of MyMethodTwo.
            CMyClass
              Constructor.
            ~CMyClass
              Destructor.
C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C-C*/


Class Method Definition Header

/*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  Method:   CMyClass::MyMethodOne

  Summary:  Short summary of purpose and content of MyMethodOne.
            Short summary of purpose and content of MyMethodOne.

  Args:     MYTYPE MyArgOne
              Short description of argument MyArgOne.
            MYTYPE MyArgTwo
              Short description of argument MyArgTwo.

  Modifies: <list of member data variables modified by this method>.

  Returns:  MYRETURNTYPE
              Short description of meaning of the return type values.
M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/


Unexported or Local Function

/*F+F++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  Function: MyLocalFunction

  Summary:  What MyLocalFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
------------------------------------------------------------------------F-F*/


Exported Function Definition Header

/*F+F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F
  Function: MyFunction

  Summary:  What MyFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F-F*/


OLE Interface Declaration Header

/*I+I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I
  Interface: IMyInterface

  Summary:   Short summary of what features the interface can bring to
             a COM Component.

  Methods:   MYTYPE MyMethodOne
               Description.
             MYTYPE MyMethodTwo
               Description.
I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I-I*/


COM Object Class Declaration Header

/*O+O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O
  ObjectClass: COMyCOMObject

  Summary:     Short summary of purpose and content of this object.

  Interfaces:  IUnknown
                 Standard interface providing COM object features.
               IMyInterfaceOne
                 Description.
               IMyInterfaceTwo
                 Description.

  Aggregation: <whether this COM Object is aggregatable or not>
O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O-O*/


All of these comment block conventions have consistent beginning and
ending token strings. This consistency supports automatic processing of
the headers in some fashion. For example, AWK scripts can be written to
filter out only the function headers into a separate text file that can
serve the basis for a specification document. Similarly, tools like the
unsupported AUTODUCK utility (currently available on the Microsoft
Developer Network Development Library CD-ROM) can be used to process the
comment blocks in these headers. The following beginning and ending tokens
are used:

  /*+     File Header Begin
  +*/     File Header End

  /*-     Plain comment block Header Begin
  -*/     Plain comment block Header End

  /*C     Class Header Begin
  C*/     Class Header End

  /*M     Method Header Begin
  M*/     Method Header End

  /*F     Function Header Begin
  F*/     Function Header End

  /*I     Interface Header Begin
  I*/     Interface Header End

  /*O     COM Object Class Header Begin
  O*/     COM Object Class Header End

These headers can also be used as visual cues for rapid scanning of source
files. They also provide convenience for rapidly getting to some source
location if you set up search strings in your editor and then 'repeat last
search' to quickly locate these headers. For example, the search string
"M+M" will locate the start of method headers, and "M-M" will locate the
beginning of the actual method definition/implementation code.


================================== END ======================================
